/*****************************************************************************
 * Copyright (C) 2003-2005 Jean-Daniel Fekete and INRIA, France              *
 * ------------------------------------------------------------------------- *
 * This software is published under the terms of the X11 Software License    *
 * a copy of which has been included with this distribution in the           *
 * license-infovis.txt file.                                                 *
 *****************************************************************************/
package infovis.panel;

import javax.swing.BoundedRangeModel;
import javax.swing.event.ChangeListener;

/**
 * 
 * Caution this is a modified version of the infovis toolkit which strips down
 * the minimal code to use the DoubleRangeSlider. Please find the orginial code
 * at: http://ivtk.sourceforge.net/.
 * <p>
 * 
 * Double version of a <code>BoundedRangeModel</code>.
 * 
 * @author Jean-Daniel Fekete
 * @version $Revision: 1.1 $
 * 
 * @see javax.swing.BoundedRangeModel
 */
public interface DoubleBoundedRangeModel extends BoundedRangeModel {
  /**
   * Returns the minimum acceptable value.
   * 
   * @return the value of the minimum property
   * @see #setMinimum
   */
  double getMinimumDouble();

  /**
   * Sets the sizeModel's minimum to <I>newMinimum</I>. The other three
   * properties may be changed as well, to ensure that:
   * 
   * <pre>
   * minimum &lt;= value &lt;= value + extent &lt;= maximum
   * </pre>
   * <p>
   * Notifies any listeners if the sizeModel changes.
   * 
   * @param newMinimum
   *          the sizeModel's new minimum
   * @see #getMinimum
   * @see #addChangeListener
   */
  void setMinimum(double newMinimum);

  /**
   * Returns the sizeModel's maximum. Note that the upper limit on the
   * sizeModel's value is (maximum - extent).
   * 
   * @return the value of the maximum property.
   * @see #setMaximum
   * @see #setExtent
   */
  double getMaximumDouble();

  /**
   * Sets the sizeModel's maximum to <I>newMaximum</I>. The other three
   * properties may be changed as well, to ensure that
   * 
   * <pre>
   * minimum &lt;= value &lt;= value + extent &lt;= maximum
   * </pre>
   * <p>
   * Notifies any listeners if the sizeModel changes.
   * 
   * @param newMaximum
   *          the sizeModel's new maximum
   * @see #getMaximum
   * @see #addChangeListener
   */
  void setMaximum(double newMaximum);

  /**
   * Returns the sizeModel's current value. Note that the upper limit on the
   * sizeModel's value is <code>maximum - extent</code> and the lower limit is
   * <code>minimum</code>.
   * 
   * @return the sizeModel's value
   * @see #setValue
   */
  double getValueDouble();

  /**
   * Sets the sizeModel's current value to <code>newValue</code> if
   * <code>newValue</code> satisfies the sizeModel's constraints.
   * 
   * Those constraints are:
   * 
   * <pre>
   * minimum &lt;= value &lt;= value + extent &lt;= maximum
   * </pre>
   * 
   * Otherwise, if <code>newValue</code> is less than <code>minimum</code> it's
   * set to <code>minimum</code>, if its greater than <code>maximum</code> then
   * it's set to <code>maximum</code>, and if it's greater than
   * <code>value+extent</code> then it's set to <code>value+extent</code>.
   * <p>
   * When a BoundedRange sizeModel is used with a scrollbar the value specifies
   * the origin of the scrollbar knob (aka the "thumb" or "elevator"). The value
   * usually represents the origin of the visible part of the object being
   * scrolled.
   * <p>
   * Notifies any listeners if the sizeModel changes.
   * 
   * @param newValue
   *          the sizeModel's new value
   * @see #getValue
   */
  void setValue(double newValue);

  /**
   * This attribute indicates that any upcoming changes to the value of the
   * sizeModel should be considered a single event.
   * 
   * <p>
   * This attribute will be set to true at the start of a series of changes to
   * the value, and will be set to false when the value has finished changing.
   * Normally this allows a listener to only take action when the final value
   * change in committed, instead of having to do updates for all intermediate
   * values.
   * <p>
   * Sliders and scrollbars use this property when a drag is underway.
   * 
   * @param b
   *          true if the upcoming changes to the value property are part of a
   *          series
   */
  void setValueIsAdjusting(boolean b);

  /**
   * Returns true if the current changes to the value property are part of a
   * series of changes.
   * 
   * @return the valueIsAdjustingProperty.
   * @see #setValueIsAdjusting
   */
  boolean getValueIsAdjusting();

  /**
   * Returns the sizeModel's extent, the length of the inner range that begins
   * at the sizeModel's value.
   * 
   * @return the value of the sizeModel's extent property
   * @see #setExtent
   * @see #setValue
   */
  double getExtentDouble();

  /**
   * Sets the sizeModel's extent. The <I>newExtent</I> is forced to be greater
   * than or equal to zero and less than or equal to maximum - value.
   * 
   * <p>
   * When a BoundedRange sizeModel is used with a scrollbar the extent defines
   * the length of the scrollbar knob (aka the "thumb" or "elevator"). The
   * extent usually represents how much of the object being scrolled is visible.
   * When used with a slider, the extent determines how much the value can
   * "jump", for example when the user presses PgUp or PgDn.
   * <p>
   * Notifies any listeners if the sizeModel changes.
   * 
   * @param newExtent
   *          the sizeModel's new extent
   * @see #getExtent
   * @see #setValue
   */
  void setExtent(double newExtent);

  /**
   * This method sets all of the sizeModel's data with a single method call.
   * 
   * The method results in a single change event being generated. This is
   * convenient when you need to adjust all the sizeModel data simultaneously
   * and do not want individual change events to occur.
   * 
   * @param value
   *          an double giving the current value
   * @param extent
   *          an double giving the amount by which the value can "jump"
   * @param min
   *          an double giving the minimum value
   * @param max
   *          an double giving the maximum value
   * @param adjusting
   *          a boolean, true if a series of changes are in progress
   * 
   * @see #setValue
   * @see #setExtent
   * @see #setMinimum
   * @see #setMaximum
   * @see #setValueIsAdjusting
   */
  void setRangeProperties(double value, double extent, double min, double max, boolean adjusting);

  /**
   * Adds a ChangeListener to the sizeModel's listener list.
   * 
   * @param x
   *          the ChangeListener to add
   * @see #removeChangeListener
   */
  void addChangeListener(ChangeListener x);

  /**
   * Removes a ChangeListener from the sizeModel's listener list.
   * 
   * @param x
   *          the ChangeListener to remove
   * @see #addChangeListener
   */
  void removeChangeListener(ChangeListener x);
}
